LightWavin' Magazine 5/LightWavin' Magazine, Issue 5 WIN-MAC (DMG Publishing)(1998).iso/mac/Dspot/sgi/READMEDSPOT1.txt

Text File | 1998-01-05 | 15KB | 397 lines

------------------------------------
README FILE for Dspot(Nag) Version 1
------------------------------------

    --> Currently available on Intel and SGI platforms <--

Special thanks to Marvin Landis for compiling the SGI version.



=================
Table Of Contents
=================

    Description
    Installation
    Dependencies
    Tested On...
    Known Limitations
    Bug Reports
     How to Purchase






-----------
Description
-----------

        Overview
        --------

Dspot is a layout/animation displacement plugin, a procedural displacement
handler/interface in LW SDK terms. Once installed, it appears as a
"Disp Map Plug-in" in Layout's Objects panel. It acts something like
a displacement effector, altering objects' geometry based on a number
of factors specified by the user. Dspot is a silly name that's sort of
an abbreviation for "displacement spot", as early tests just used a
null item as the effector.  The Dspot plugin is copyright 1997
by D.J. Hudek.


Dspots can be used for a variety of "fun" effects. Put a radial style
attractor dspot in the mouth of a hand-held vacuum and suck in a buick.
Put a parallel style repeller in the vicinity and fly a bird into a plate
glass window (smooshing flat as it hits). Use a parallel style attractor
to allow a monster to emerge from the ground as the attraction is lessened,
or a giant cartoon electro-magnet to deform and attract the evil robot,
or use a sinusoidal modifier on a radial dspot and allow a tophat to beat
like a heart, or use a radial style dspot as a "force-field" around a hero
object and it can push/deform other objects out of the way as it barges
its way along, or create a small hole in a high altitude jet and use an
attractor dspot to squirt people and other items out of it, or use
several different styles with differing modifiers scattered about in
space and deform a ship as it flies through, or or or... well, there are
many many combinations of parameters each with different effects...
it's fun to experiment and play around.   :-)



Dspots act on an object-by-object basis, applied via Layout's Objects
Panel, under the "Disp Map Plug-ins" widget. Any object, light, or camera
may act as a Dspot for any object or objects. An object may have multiple
Dspots which affect it. For each, one has control over a number of
parameters which determine the amount of displacement a dspot will apply
to an object at any point in time:
    * Item to act as a Dspot for this object
    * Attract or Repel
    * Various displacement styles (radial, plus 4 types of parallel)
    * InnerRadius (may be animated)
    * OuterRadius (may be animated)
    * Raw displacement to apply
    * Displacement strength falloff (none, 1/d, 1/d**2, d)
    * Strength modifier (none, sinusoid with specified period and phase,
                 or animatable via control item)


If a particular point on the object is further away than the outside radius,
no displacement is applied.

If it is between the outer and inner radius, the displacement is determined
by "(raw displacement) * (strength falloff) * (modifier)"

If a point is closer than the inner radius, it is pushed back (except for
one of the parallel styles, points may not invade a dspot's inner radius).

The inner radius, the outer radius, and the strength modifier (and
therefore the displacement to apply) may all be animated.

Experiment with the settings and have fun.







        Invocation
        ----------
After installation of the plugin, Dspots can be invoked for an object
by means of the "Disp Plug-ins" option in the Objects Panel. Once selected,
the user interface is accessed via the associated "Options" button.



        User Interface
        --------------
The first menu presented gives one the option of creating a new Dspot,
modifying an existing Dspot (if any have been created), or Deleting
a Dspot (again, only makes sense if some have been created). The bottom
half of the menu provides a popup list of all the Dspots currently
created for the object (if any), from which to choose for the modify
or delete action.

        [[ Create A New Dspot ]]

The first time this is invoked for an object, a funny question will appear
at the top (see Known Limitations, below). The SDK isn't too good about
always accurately letting the software know which object is the subject
of interest, so the first item may claim "amnesia" and ask you to supply
the name of the object for which you intend to add Dspots. An odd workaround.
This should only happen the first time you create a dspot for the object.

Most of the remaining items are self-explanatory.

The next widget asks you to specify which object, light or camara will
be acting as a Dspot with the set of parameters you are about to supply.

The next widget asks whether the Dspot should Attract or Repel.

The next three widgets concern the inner and outer radii of the Dspot.
They define space in which the Dspot may exert displacement upon the object,
as described above in the overview. If one so chooses, the radii values
may be changed over time by use of a control item (which will specified at
the bottom of the menu). If used, the inner radius will be multiplied by the
control item's X channel value, while the outer radius will be multiplied
by the item's Y channel value. Of course, one should keep the inner radius
value less than the outer radius. The default is to use static radii
values and not use the control item for dynamic scaling.

The next widget asks for the raw displacement to apply to points when
they are within range of the Dspot. This raw value will be altered
based upon the strength falloff and strength modifier values which
are specified below. The basic equation for the displacement to apply
is rawDisplacement x falloff x modifier.

The next widget asks for what style of displacement you desire. There
are 5 options:
    Radial
    Parallel with X constrained
    Parallel with Y constrained
    Parallel with Z constrained
    Parallel with no contraints

The Radial style applies a radial displacement (imagine a black hole
for attractors, or an expanding bubble for repellers). The displacement
radiates in/out evenly from the center pivot point of the Dspot item.
Points on the object will be displaced along different normals; each
along a normal from the particular point to the Dspot pivot point.
The inner radius of the Dspot is a no-man's-land. A point is not allowed
within the inner radius and will always be displaced outside of it.

The Parallel options apply displacement to all points using a single
common normal... from the object's pivot point to the Dspot's pivot point.
While the Radial displacement causes the object to shrink or grow,
the parallel tends to keep the objects shape (of course, it will stretch
or compress depending on the other parameters, but it doesn't shrink down
to a tiny point as can happen with radial displacement). The first
three styles are concerned with actions related to the inner radius.
They allow one to set up imaginary parallel planes related to the inner
radius between which points are not allowed (imagine two large plate
glass windows, spaced on either side of the Dspot pivot point an
innerRadius away, and aligned on the X, Y, or Z planes (as specified).
Points may be displaced up to the planes, but not between them).
The last Parallel option does not use the imaginary plane constraint,
points may be displaced within the inner radius.

The next widget in the menu asks about displacement strength falloff.
Choices are :
    Constant (no falloff)
    1 / Distance
    1 / Distance**2
    Distance - InnerRadius
The first option specifies no strength falloff, the next two specify
that the strength is generally inversely proportional to distance or
distance squared, and the last one specifies that the strength is
generally proportional to the distance (they are actually scaled by
the inner to outer distance).

The next widget allows one to specify a further strength modifier.
Choices are:
    None
    Sinusoidal
    Control Item
None means no further modifications. Sinusoidal indicates a sine modification,
using the period and phase specified in the next two widgets. Control Item
indicates that the Z Channel value of the control item (specified at
the bottom of the menu, also used to control the inner/outer radii
with its X and Y channels), will be used to further modify the displacement.
As implied by the sinusoidal option (and certainly available to the
control item), the Dspot attraction or repulsion may be reversed over
time... a negative displacement while attracting is equivalent to a
positive displacement while repelling and vice versa.

The next two widgets are only used if the sinusoidal modifier was selected.
They allow one to specify the period (in seconds) and phase (in radians)
for the modifying sine wave.

The final widget is only used if one wants to animate the inner/outer
radii and/or the strength modifications. The X channel values of the
specified item may be used to alter the inner radius, the Y channel
value may be used to modify the outer radius, and the Z channel value
may be used to modify the displacement strength. The control item allows
one fairly arbitrary control of the Dspot behaviour.




        [[ Modify An Existing Dspot ]]

This action allows one to modify the Dspot selected in the main menu.
Upon invocation, it will bring up a menu that is almost identical to that
used by Create New, except for the fact that the "amnesia" related question
(what object am I anyway?) is always present (unlike the Create New Dspot
when it is only present the first time a Dspot is added to an item).
This will come in handy if one alters a scene such that Lightwave changes
the object names and IDs on us (see Known Limitations below).
The remaining widgets are identical to those described above in the
Create New section.


        [[ Delete A Dspot ]]

This action deletes the Dspot selected in the main menu.






------------
Installation
------------
If you are reading this, presumably you knew to unzip the downloaded
file  :-)

After unzipping, there should be two new files:
    READMEDSPOT1.txt (this file)
        and either
    DspotNagV1.p     (the plugin if you downloaded the Intel version)
        or
    sgiDspotNagV1.p  (the plugin if you downloaded the SGI version)

Simply move or copy the plugin file to whereever you keep your Layout
plugins:
    On Intel Platform, typically DRIVE:\newtek\plugins\layout
    On SGI Platform, typically /usr/lightwave/plugins/layout

Fire up Lighwave(Layout) and use Options/Add Plug-ins to add the plugin.
If you do not already have the standard lwpanels.p added, be sure to do so
before first activating Dspot. (If you so desire, you could also have
edited the layout config file directly, but using the Add Plugin feature
is easier and less prone to typing errors :-) )

Once Dspot has been added, you should see it as an option in the
Object Panel/Disp Map Plug-ins list.






------------
Dependencies
------------
lwpanels.p

Dspot relies on the services provided by the Lwpanels.p plugin.
It must be added to Layout before this plugin will work.



------------
Tested On...
------------
Lightwave 5.0m on an Intel platform
    - Windows NT Workstation 4.0 on a Dual PII system

Lightwave 5.0 on an Indigo 2 (IRIX 6.2) and an O2 (IRIX 6.3)

Tested using relatively simple scenes, using a representative
sample of the various options.

The version of Lwpanels.p used in testing on the Intel platform
was dated 6/29/96 and came with the vanilla lightwave installation
(version 5.0m).

This plugin should work with Lightwave version 5.5 as well.





-----------------
Known Limitations
-----------------
There are a few oddities imposed by the LW SDK.
If the SDK changes in the future, these may be reduced/removed.

The main oddities have to do with object naming and IDs. We don't
always get the correct IDs when we expect them, and both IDs and
names fluctuate depending on how the user manipulates the scene
elements, so in some menus the user is requested to supply the correct
object name, from which we can derive its current ID.

After creating clones of an object which used Dspots, one must open
the Modify Dspot menu for each and supply them with their current name.
Depending on if the base object had already been cloned before or not,
its name may have changed and again, the Modify Dspot menu should
be used to supply the new name.

When multiple copies of an object are present in a scene and then ones in
the middle deleted (e.g., cows 1 to 6 originally, then change your mind
and delete cow(3)), some names and ids are changed, so again, one may
need to use the Modify Dspot menu to supply the correct name




  ** SPECIAL --->  ONLY FOR LIMITED TRIAL VERSION:
This version of the plugin is intended only for a limited time
trial use, to allow the user to determine if it's helpful or not.
If it proves useful, the user is expected to purchase Dspots (see below).

The nagging trial version has some artificial limitations. First, it
will not save or load Dspot to/from the scene file. Second, it will
only apply Dspot displacement for frames 1 to 30. Finally, the Modify
menu will only accept changes for up to 10 times; after that, one
must delete and create new to effect modifications, and it will
nag you about purchasing the product if you try the modify option.

Of course, these limitations apply only to this trial version; the
actual product will save and load, displace past frame 30, and let
you modify to your heart's content.  :-)





-----------
Bug Reports
-----------

I tried to test a representative sample of the possible combinations,
but some bugs have probably slipped through. If you'd care to submit
any bug reports, they can be mailed to my aol account: [e-mail]
(the ultranet account is not checked as frequently).




---------------
How to Purchase
---------------
If you've used this version and don't find it to be useful, sorry,
but thanks for giving it a test drive.  :-)    I may have others in
the future that will prove more satisfactory.

If it does prove helpful to you, please register and purchase it.
The introductory purchase price is $50 and may be sent
(check or money order) to the following address:

    D.J. Hudek
    17 Bruce St.
    Grafton, MA  01519

If you include your email address, a non-crippled/non-nagging version
of Dspot.p will be sent in return. Be sure to specify which platform
you will run it on (Intel or SGI).

I can't imagine that anyone who would use this doesn't have an email
address (???) but if so, we could probably arrange a floppy mailing for
a nominal extra fee.

Thanks,
d.j.hudek